using System;
using System.Collections;

namespace Sedna.Core.Persistence
{
	/// <summary>
	/// inftrastructure facility that provides mechanisms for
	/// executing either bare HQL queries or quesries based upon the
	/// filter state
	/// 
	/// This facility is mostly part used by Grid controllers whereby they
	/// get a state of a particular filter, executes them and maps to a Grid
	/// </summary>
	public interface IHqlExecutor
	{
		/// <summary>
		/// executes a HQL query with all the parameters already installed
		/// </summary>
		/// <param name="hqlQuery">completely created (including injected parameters) HQL query</param>
		/// <returns>
		/// either a collection of objects or an array of fields (this depends on the HQL query)
		/// </returns>
		ICollection Execute(string hqlQuery);

		/// <summary>
		/// executes a HQL query with all the parameters already installed 
		/// this method allows to set up the first record (zero-based) and the amount of records
		/// to be selected
		/// </summary>
		/// <param name="hqlQuery">completely created (including injected parameters) HQL query</param>
		/// <param name="start">first record to return</param>
		/// <param name="amount">total amount of records to return</param>
		/// <returns>
		/// either a collection of objects or an array of fields (this depends on the HQL query)
		/// </returns>
		ICollection Execute(string hqlQuery, int start, int amount);

		/// <summary>
		/// executes a query that is created from an instance of a IFilterState
		/// this is a preferred way of using the executor since hardcoding the 
		/// HQL (or even SQL) queries shall be considered as a last resort and
		/// developers are discouraged from using such approaches in favour of 
		/// automated ICriteria generation (<seealso cref="IExternalCriteriaFilterState"/>)
		/// </summary>
		/// <param name="filterState">
		/// an instance of either a <see cref="ICriteriaFilterState"/> 
		/// or <see cref="IExternalCriteriaFilterState"/>
		/// </param>
		/// <returns>
		///	an instance of a <see cref="IQueryResult"/> that contains among everything 
		///	else the amount of total data that can be retrieved from the underlying DB
		///	</returns>
		IQueryResult Execute(IFilterState filterState);

        long GetTotalAmount(IFilterState filterState);
	}
}
